# Snow CLI User Documentation - First Time Configuration

Welcome to Snow CLI! Agentic coding in your terminal.

## First Time Configuration

### 1. Launch from Any Directory

1. Type `snow` to start Snow CLI or click the launch icon in the IDE plugin
2. Snow CLI's default language is `English`. You can go to `Language Settings` to modify your language preference

   ![alt text](../images/image4.png)

### 2. Enter Configuration Interface

After setting your language preference, go to `API and Model Settings`

![alt text](../images/image5.png)

The configuration interface provides comprehensive AI service configuration capabilities, supporting multiple profile management and rich model parameter settings.

## Detailed Configuration Options

### Profile Management

**Purpose**: Manage multiple configuration sets for quick switching between different scenarios

**Operations**:

- Press Enter to access the profile selection interface
- Use up/down arrow keys to select profiles
- The currently active profile will display a green ✓ mark

**Quick Actions**:

- Press `n` key: Create new profile (requires entering profile name)
- Press `d` key: Delete current profile (the default profile cannot be deleted)

**Important Notes**:

- Each profile independently saves all settings
- Switching profiles immediately loads all settings from that profile

### Basic Configuration

#### Base URL (Required)

**Purpose**: Base address of the API service

**Configuration Method**:

- Press Enter to enter edit mode
- Input the complete API address
- Press Enter again to confirm

**Standard Addresses**:

![alt text](../images/image6.png)

1. **OpenAI Chat Completion**

   ```
   https://api.openai.com/v1
   ```

   For OpenAI's standard chat completion API

2. **OpenAI Responses**

   ```
   https://api.openai.com/v1
   ```

   For OpenAI's response API with reasoning capabilities

3. **Gemini**

   ```
   https://generativelanguage.googleapis.com/v1beta
   ```

   Google Gemini API service address

4. **Anthropic**
   ```
   https://api.anthropic.com/v1
   ```
   API service address for Claude models

**Important Notes**:

- Supports proxy or third-party relay service addresses
- Ensure the address format is correct, starting with `https://`
- Address typically includes version number at the end (e.g., `/v1`)

#### API Key (Required)

**Purpose**: Access key for API service

**Configuration Method**:

- Press Enter to enter edit mode
- Input the complete API Key
- Input will be automatically hidden and displayed as `*` characters
- Press Enter again to confirm

**Important Notes**:

- API Keys typically start with specific prefixes (e.g., `sk-` for OpenAI)
- Keep your API Key secure to prevent disclosure
- Will only display as asterisks, never in plain text

#### Request Method

**Purpose**: Select API calling method; different methods support different features

**Available Options**:

- **OpenAI Chat Completion**: Standard OpenAI chat API
- **OpenAI Responses**: OpenAI API with reasoning mode support
- **Gemini**: Google's Gemini model
- **Anthropic**: Claude model

**Configuration Method**:

- Press Enter to open selection list
- Use up/down arrow keys to select
- Press Enter to confirm

**Important Notes**:

- Different request methods display different advanced configuration options
- When switching request methods, specific feature configurations will automatically adjust

#### System Prompt (Optional)

**Purpose**: Select which system prompt to use for the current profile

**Available Options**:

- **Follow Global (None)**: Use global settings, no system prompt currently activated
- **Follow Global (Name)**: Use the system prompt activated in global settings
- **Not Use**: Explicitly disable system prompt, even if there's an activated global prompt
- **Select Specific Prompt**: Choose from the list of configured system prompts

**Configuration Method**:

- Press Enter to open selection list
- Use up/down arrow keys to select
- Press Enter to confirm

**Description**:

- System prompts can be created and managed in the "System Prompt Management" interface
- Profile-level settings override global settings
- Selecting "Not Use" allows you to temporarily disable system prompts in specific scenarios

#### Custom Headers (Optional)

**Purpose**: Select which custom headers scheme to use for the current profile

**Available Options**:

- **Follow Global (None)**: Use global settings, no headers scheme currently activated
- **Follow Global (Name)**: Use the headers scheme activated in global settings
- **Not Use**: Explicitly disable custom headers, even if there's an activated global scheme
- **Select Specific Scheme**: Choose from the list of configured headers schemes

**Configuration Method**:

- Press Enter to open selection list
- Use up/down arrow keys to select
- Press Enter to confirm

**Description**:

- Custom headers schemes can be created and managed in the "Custom Headers Management" interface
- Profile-level settings override global settings
- Selecting "Not Use" allows you to temporarily disable custom headers in specific scenarios

### Advanced Configuration

#### Enable Auto Compress

**Purpose**: Automatically compress long text content to reduce token consumption

**Default**: Enabled

**Configuration Method**:

- Press Enter or Space key to toggle Enabled/Disabled status
- Displays "Enabled" or "Disabled"

**Recommendation**: Enabling can reduce API call costs but may lose some context details

#### Show Thinking

**Purpose**: Display AI's reasoning and thinking process in the interface

**Default**: Enabled

**Configuration Method**:

- Press Enter or Space key to toggle Enabled/Disabled status
- Displays "Enabled" or "Disabled"

**Recommendation**: Enabling helps understand AI's reasoning process, useful for debugging and understanding results

### Anthropic-Specific Configuration

When selecting the `Anthropic` request method, the following configuration options will appear:

#### Anthropic Beta

**Purpose**: Enable Anthropic's Beta version features

**Default**: Disabled

**Configuration Method**:

- Press Enter or Space key to toggle Enabled/Disabled status

**Important Notes**: Beta features may be unstable, use with caution

#### Anthropic Cache TTL

**Purpose**: Set the expiration time for prompt caching

**Available Options**:

- `5m`: 5 minutes
- `1h`: 1 hour

**Default**: 5 minutes

**Configuration Method**:

- Press Enter to open selection list
- Select cache duration
- Press Enter to confirm

**Description**: Longer cache times can reduce token consumption for repeated content

#### Thinking Enabled

**Purpose**: Enable Claude's extended thinking feature

**Default**: Disabled

**Configuration Method**:

- Press Enter or Space key to toggle Enabled/Disabled status

**Description**: When enabled, AI will perform deeper reasoning

#### Thinking Budget Tokens

**Purpose**: Set the maximum token count for extended thinking mode

**Default**: 10000

**Range**: Minimum value 1000

**Configuration Method**:

- Press Enter to enter edit mode
- Input number (supports backspace deletion)
- Press Enter to confirm

**Important Notes**:

- Larger thinking budget enables deeper AI reasoning but consumes more tokens
- If input value is below minimum, it will automatically adjust to minimum value when saved

### Gemini-Specific Configuration

When selecting the `Gemini` request method, the following configuration options will appear:

#### Gemini Thinking Enabled

**Purpose**: Enable Gemini's thinking and reasoning feature

**Default**: Disabled

**Configuration Method**:

- Press Enter or Space key to toggle Enabled/Disabled status

#### Gemini Thinking Budget

**Purpose**: Set the budget value for Gemini thinking mode

**Default**: 1024

**Range**: Minimum value 1

**Configuration Method**:

- Press Enter to enter edit mode
- Input number (supports backspace deletion)
- Press Enter to confirm

### OpenAI Responses-Specific Configuration

When selecting the `OpenAI Responses` request method, the following configuration options will appear:

#### Responses Reasoning Enabled

**Purpose**: Enable OpenAI's reasoning feature

**Default**: Disabled

**Configuration Method**:

- Press Enter or Space key to toggle Enabled/Disabled status

#### Responses Reasoning Effort

**Purpose**: Set the intensity level of reasoning mode

**Available Options**:

- `LOW`: Low-intensity reasoning
- `MEDIUM`: Medium-intensity reasoning
- `HIGH`: High-intensity reasoning
- `XHIGH`: Ultra-high intensity reasoning (only supported in responses method)

**Default**: HIGH

**Configuration Method**:

- Press Enter to open selection list
- Use up/down arrow keys to select intensity
- Press Enter to confirm

**Important Notes**: Higher reasoning intensity provides deeper reasoning but increases time and token consumption

### Model Configuration

#### Advanced Model

**Purpose**: Primary model for complex tasks

**Configuration Method**:

1. Press Enter to automatically fetch available model list (requires correct Base URL and API Key configuration)
2. If fetching fails, will automatically enter manual input mode
3. Can use alphanumeric input for fuzzy search filtering
4. Select "Manual Input" option to manually enter model name
5. Press `m` key to quickly enter manual input mode

**Common Model Examples**:

- OpenAI: `gpt-4`, `gpt-4-turbo`, `gpt-4o`
- Claude: `claude-3-5-sonnet-20241022`, `claude-3-opus-20240229`
- Gemini: `gemini-2.0-flash-exp`, `gemini-pro`

**Recommendation**: Choose more powerful models for complex programming tasks

#### Basic Model

**Purpose**: Auxiliary model for simple tasks

**Configuration Method**: Same as Advanced Model

**Common Model Examples**:

- OpenAI: `gpt-3.5-turbo`, `gpt-4o-mini`
- Claude: `claude-3-haiku-20240307`
- Gemini: `gemini-flash`

**Recommendation**: Choose models with fast response speed and lower cost

#### Max Context Tokens

**Purpose**: Maximum context window size supported by the model

**Default**: 4000

**Range**: Minimum value 4000

**Configuration Method**:

- **Setup UI (TUI)**: Press Enter to edit → type a number → Enter to confirm
- **Preferred for automation / Agent / headless** (hot-set; no same-process restart):
  - View: `snow cmd config status --json`
  - Set: `snow cmd config set maxContextTokens=470000 --json`
  - Agent tool: `session-command-run` → `command: "config.set"`, `args: "maxContextTokens=470000"`
- Full details: [09.4.Configuration and Management Commands](./09.4.Configuration%20and%20Management%20Commands.md) (`/config`) and [29.Session Command Control Plane](./29.Session%20Command%20Control%20Plane.md)

**Common Model Context Capacities**:

- Claude 3.5 Sonnet: 200000
- GPT-4 Turbo: 128000
- GPT-4: 8192
- Gemini 2.0 Flash: 1000000
- Gemini Pro: 32768

**Important Notes**:

- Must be set to the actual context size supported by the model
- Setting too high will cause API call failures
- Setting too low will limit conversation length
- Prefer `config.set` / `config.status` over hand-editing `~/.snow/config.json` or `profiles/*.json`
- TUI slash `/config` is **only** YAML export/import — you **cannot** set context with `/config 12000`

#### Max Tokens

**Purpose**: Maximum token count allowed for single response generation

**Default**: 4096

**Range**: Minimum value 100

**Configuration Method**:

- **Setup UI (TUI)**: Press Enter to edit → type a number → Enter to confirm
- **Preferred for automation / Agent / headless**: `snow cmd config set maxTokens=8192 --json` (can be combined with `maxContextTokens` in one call)
- See [09.4.Configuration and Management Commands](./09.4.Configuration%20and%20Management%20Commands.md) and [29.Session Command Control Plane](./29.Session%20Command%20Control%20Plane.md)

**Common Model Output Capacities**:

- Claude 3.5 Sonnet: 64000
- GPT-4 Turbo: 4096
- GPT-4: 8192
- Gemini 2.0 Flash: 8192

**Important Notes**:

- Different models support different maximum output token counts
- Setting too high will increase response time and cost
- Recommend setting reasonably based on actual needs

## Configuration Interface Operations

### Basic Operations

- **Up/Down Arrow Keys**: Move between configuration items
- **Enter Key**: Enter edit mode or confirm input
- **Esc Key**: Save configuration and exit
- **Ctrl+S / Cmd+S**: Quick save configuration
- **Space Key**: Toggle switch-type configuration items (e.g., Enable/Disable)

### Navigation Tips

- Configuration interface displays current position at top: `(Current item/Total items)`
- When configuration items exceed 8, will automatically scroll
- Currently selected configuration item displays `❯` marker

### Enhanced Model Selection Features

In the model selection interface:

- **Alphanumeric Input**: Real-time filtering of model list
- **Backspace**: Delete filter characters
- **Esc Key**: Exit selection interface
- **m Key**: Quick entry to manual input mode

### Enhanced Number Input

When editing token-related configurations:

- **Number Keys**: Append digits
- **Backspace/Delete**: Delete last digit
- **Enter Key**: Confirm and automatically validate minimum value

## Configuration Validation

The system will automatically validate when saving configuration:

1. **Required Field Check**: Base URL and API Key must be filled
2. **Format Validation**: Check if Base URL format is correct
3. **Value Range**: Automatically adjust token configurations above minimum values
4. **Request Method Matching**: Validate compatibility between selected model and request method

**Error Messages**:

- Red error information will display at bottom of interface when validation fails
- Can try saving again after fixing errors

## Configuration File Storage

- **Main configuration file (current)**: `~/.snow/config.json`
- **Profile directory (current)**: `~/.snow/profiles/`
- **Legacy path**: older docs may still mention `~/.snowcli/...`; prefer the `~/.snow` tree in use on your machine
- **Auto Save**: Automatically saves to the currently active profile when exiting the configuration interface
- **Automation writes**: `config.set` updates `config.json` and the active profile, with same-process TUI hot-refresh

## FAQ

### 1. Unable to fetch model list?

**Solution**:

- Check if Base URL and API Key are correct
- Check network connection and proxy settings
- If it continues to fail, use manual input mode (press `m` key)

### 2. Configuration doesn't take effect after saving?

**Solution**:

- Confirm you have saved configuration by pressing Esc or Ctrl+S
- Restart Snow CLI to ensure configuration is loaded
- Check if the correct profile is selected
- If you used `snow cmd config set`: same-process TUI hot-refreshes; an **external** process may not refresh an already open TUI until reload/restart

### 3. Token limit exceeded error?

**Solution**:

- Check Max Context Tokens: `snow cmd config status --json`
- Confirm it doesn't exceed the model's actual supported context size
- Reduce Max Tokens if needed: `snow cmd config set maxTokens=… --json`
- Prefer: `snow cmd config set maxContextTokens=… --json` (do not hand-edit JSON)

### 4. Configuration lost after switching request methods?

**Explanation**: Specific configuration items for different request methods (such as Anthropic's Thinking feature) will automatically show/hide based on the current method. Configuration values are still saved and will be restored when switching back.

### 5. How do I change context via command/Agent instead of hand-editing files?

**Preferred path** (session-command control plane):

```bash
snow cmd config status --json
snow cmd config set maxContextTokens=470000 --json
```

- Agent: `session-command-run` → `config.set` / `config.status`
- Do not prefer hand-editing `~/.snow/config.json` or `profiles/*.json`
- TUI `/config` is YAML export/import only — see [09.4.Configuration and Management Commands](./09.4.Configuration%20and%20Management%20Commands.md) and [29.Session Command Control Plane](./29.Session%20Command%20Control%20Plane.md)

## Configuration Best Practices

1. **First-Time Configuration**: First set Basic configuration (Base URL, API Key, Request Method), then configure advanced features
2. **Multi-Scenario Usage**: Create different profiles for different projects
3. **Cost Optimization**: Reasonably set Max Tokens, enable Auto Compress feature
4. **Performance Optimization**: Choose appropriate models based on task complexity, use Basic Model for simple tasks
5. **Debugging Recommendation**: Enable Show Thinking to view AI reasoning process, helpful for understanding and optimizing prompts
6. **Automated limits**: use `config.set` for context/output/model names; keep API keys in the setup UI